home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / amok_lha / amok03.lha / IntuiStruct1.3 / Doc.textcraft (.txt) next >
IFF Formatted Text  |  1993-08-15  |  18KB  |  217 lines
  1. Vorwort
  2. Dieses Modul entstand an dem Tag, an dem ich bemerkte, daß mein Listing bereits ca. 500 Zeilen lang war, und ich erst ein Window mit einem Menu und einigen Gadgets programmiert hatte...
  3. Es beinhaltet schon oft Dagewesenes (Hilfen zum Ã–ffnen von Screens und Windows) aber auch Interessantes und Neues (Elegante Unterstützung von Images, Gadgets und Menus).
  4.  
  5. Neu: Version 1.3
  6. Diese Version enthält zusätzlich Routinen zum Erzeugen von Borders und Requesters. Außerdem kann man seine eigene AllocMem-Prozedur angeben (Version <1.1 benutzte immer nur Heap).
  7. Beachten Sie bitte auch die Ã„nderungen dieser Dokumentation. Es wurden einige mißverständliche Stellen verbessert.
  8.  
  9. Copyright-Hinweise
  10. "IntuiStruct" ist Public Domain Software, dh. jeder darf es umsonst benutzen und sooft und für wen er will kopieren. Bedingung ist allerdings, daß die Kopierhinweise (CopyInfo) beachtet werden. Lesen Sie bitte das in diesem Verzeichnis befindliche ReadMe-File.
  11.  
  12. Screens, Windows, Text, Gadgets
  13. Die folgenden Prozeduren sind (fast) selbsterklärend: Die Felder des entsprechenden RECORDs werden auf die Ã¼bergebenen Parameter gesetzt (die Namen der Parameter sind meist gleich oder Ã¤hnlich derjenigen des Intuition-DEFINITION-MODULEs). Es werden immer alle benötigten Felder belegt, auch wenn die Prozedur weniger Parameter hat. Die Default-Werte der automatisch initialisierten Felder werden bei der folgenden Beschreibung angegeben.
  14.  
  15. StructScreen(NewScreen, depth, detailPen, blockPen, viewModes, type, defaultTitle);
  16. öffnet den Screen noch nicht sondern Ã¼bergibt nur die NewScreen- Struktur, sodaß vor OpenScreen() noch Werte verändert werden können. Nicht verlangte Parameter werden folgendermaßen initialisiert:
  17. leftEdge:=0;topEdge:=0;height:=stdScreenHeight;
  18. font:=NIL;gadgets:=NIL;customBitmap:=NIL;
  19. IF hires IN ViewModes THEN width:=640 ELSE width:=320 END
  20.  
  21. StructWindow(NewWindow, leftEdge, topEdgr, width, height, detailPen, blockPen, idcmpFlags, flags, title, screen, type);
  22. öffnet das Window noch nicht sondern Ã¼bergibt nur die NewWindow- Struktur, sodaß vor OpenWindow() noch Werte verändert werden können. Nicht verlangte Parameter werden folgendermaßen initialisiert:
  23. firstGadget:=NIL;checkMark:=NIL;bitMap:=NIL;minWidth:=0;
  24. minHeight:=0;maxWidth:=0;maxHeight:=0
  25.  
  26. StructText(IntuiText, frontPen, backPen, drawMode, leftEdge, topEdge, iText, nextText);
  27. initialisiert eine IntuiText-Struktur, nicht angegebene Werte:
  28. iTextFont:=NIL
  29.  
  30. StructGadget(Gadget, leftEdge, topEdge, width, height, flags, activation, gadgetType, gadgetRender, gadgetText, mutualExclude, gadgetID, nextGadget);
  31. initialisiert eine Gadget-Struktur, nicht angegeben Werte:
  32. selectRender:=NIL;specialInfo:=NIL;userData:=NIL;
  33. "mutualExclude" siehe Abschnitt weiter unten.
  34. StructProp(PropInfo, flags, horizPot, vertPot, horizBody, vertBody);
  35. initialisiert eine PropInfo-Struktur, die mit 
  36. Gadget.specialInfo:=ADR(PropInfo)
  37. an das Gadget geknüpft werden kann. Sonstige Parameter:
  38. keine (werden nur von Intuition selbst verwendet)
  39.  
  40. StructString(StringInfo, Buffer(*ARRAY OF CHAR!*), UndoBuffer(*ARRAY OF CHAR!*));
  41. initialisiert die StringInfo-Struktur folgendermaßen:
  42. buffer:=ADR(Buffer);undoBuffer:=ADR(UndoBuffer);bufferPos:=0;
  43. maxChars:=HIGH(Buffer);dispPos:=0;
  44. alle anderen Felder werden nicht initialisiert.
  45. Verknüpfung mit der Gadget-Struktur siehe StructProp.
  46. Mit "StructString" kann auch ein Integergadget erzeugt werden, wenn zusätzlich das longint-Flag der Gadget-Struktur gesetzt und das longInt-Feld der StringInfo initialisiert wird.
  47.  
  48. Mutual exclusion - gegenseitiger Ausschluß von Gadgets
  49. Damit ist gemeint, daß beim Anklicken eines bestimmten Gadgets automatisch andere abgeschaltet werden (was man bei Attribut-Items von Menus schon gewohnt ist). Im Intuition Reference Manual steht, diese Funktion sei noch nicht implementiert aber bereits vorgesehen. Sie werde in einer zukünftigen Version von Intuition verfügbar sein. Wer es aufgegeben hat, darauf zu warten, wird sich Ã¼ber die Prozedur
  50.  
  51. ExcludeGadget(Gadgets, Window, Requester, Mask)
  52.  
  53. freuen. Man ruft sie mit folgenden Parametern auf, nachdem man erkannt hat, daß ein Gadget, das andere ausschließen soll, aktiviert wurde.
  54.  
  55. Gadgets: Zeiger auf das erste User(!)-Gadget des Windows oder Requesters. Vorsicht: nicht den Zeiger Window.firstGadget verwenden! Er zeigt auf das erste System-Gadget des Windows.
  56. Window: Zeiger auf das Window, in dem sich das Gadget befindet
  57. Requester: Zeiger auf den Requester, falls es sich um das Gadget eines Requesters handelt, ansonsten NIL
  58. Mask: Maske der auszuschließenden Gadgets (gesetztes Bit=ausschließen, gelöschtes=unverändert lassen). Bit 0 steht für das erste Gadget in der verketteten Liste der User-Gadgets, Bit 1 für das zweite usw.
  59. Natürlich ist "mutual exclusion" nur bei toggleSelect-Gadgets sinnvoll, wenig Sinn haben auch Gadgets, die sich selbst ausschließen.
  60. Am besten wird die Maske im dafür vorgesehenen Feld der Gadget-Struktur abgelegt. Der Aufruf lautet dann etwa:
  61.  
  62. ExcludeGadget(GadgetStripPtr, MeinWindow, NIL,
  63. aktivesGadget.mutualExclude);
  64.  
  65. Entgegen der sonst Ã¼blichen Methode wird nicht RefreshGadgets( GadgetStripPtr,...) aufgerufen, was alle Gadgets neu zeichnet. Nur die betroffenen Gadgets werden neu gezeichnet. Dies verhindert das sonst, besonders bei sehr vielen Gadgets pro Window, zu beobachtende "Zucken" beim Anklicken eines Gadgets.
  66.  
  67. Neu: Requester
  68.  
  69. StructRequest(Requester, leftEdge, topEdge, width, height, reqGadget, reqBorder, reqText, backFill);
  70.  
  71. initialisiert eine Requesterstruktur. Defaultwerte:
  72. flags:=RequesterFlagSet[];
  73.  
  74. Images elegant erzeugt
  75. Jetzt ist Schluß mit dem Ã„rger mit Hexadezimalen Zahlen, mit umständlicher Erzeugung der Image-Struktur und mit der Ungewißheit, ob die Bitplanes jetzt wirklich im ChipMem liegen. Hier ein Beispiel mit StructImage:
  76.  
  77. StructImage(Smily,X,Y,24,18,1(*depth*),[0,1](*PlanePick*),
  78. [](*PlaneOnOff*),NIL(*nextImage*));
  79. Long(000000001111111100000000L);
  80. Long(000001110000000011100000L);
  81. Long(000110000000000000011000L);
  82. Long(001000000000000000000100L);
  83. Long(010000110000000011000010L);
  84. Long(010000110000000011000010L);
  85. Long(100000000000000000000001L);
  86. Long(100000000000000000000001L);
  87. Long(100000000000000000000001L);
  88. Long(100001100000000001100001L);
  89. Long(010000011100001110000010L);
  90. Long(010000000011110000000010L);
  91. Long(001000000000000000000100L);
  92. Long(000110000000000000011000L);
  93. Long(000001110000000011100000L);
  94. Long(000000001111111100000000L);
  95. ImageEnd;
  96.  
  97. ChipMem für die Bitplane(s) wird automatisch alloziert und bei Programmbeendigung freigegeben, ohne daß man sich darum kümmern muß. Nach ImageEnd ist das Image zur Verwendung bereit.
  98. Man muß lediglich darauf achten, daß die Anzahl der Long() bzw Word() Aufrufe mit der Anzahl der für die Image-Bitplane(s) benötigten (Lang-)Wort Ã¼bereinstimmt. Sonst wird mit einer Fehlermeldung abgebrochen.
  99. Besteht das Image aus mehreren Bitplanes, so werden diese einfach nacheinander mit Word() oder Long() angeführt. Hätte obiges Beispiel 2 Bitplanes so kämen also nach den ersten 18 Long()s nocheinmal 18 für die zweite Bitplane.
  100. Ist das Image breiter als 32 Bit, dann stehen in einer Zeile mehrere Long()s und Word()s. Beachten Sie, daß Sie immer ein Vielfaches von 16 Bits angeben müssen, z.B. für ein 40 Pixel breites Image:
  101. Long(11000101011101010001100001101001L);Word(1001110100000000L);
  102. Die letzten 8 Bits haben keine Bedeutung mehr, müssen aber angeführt werden.
  103.  
  104. Neu: mit FreeImage(Image) kann das belegte Chip-Ram (Image.imageData) wieder freigegeben werden.
  105.  
  106. Neu: Borders
  107. Ähnlich wie Images werden auch die Border Strukturen erzeugt. Die Anweisungen StructBorder und BorderEnd umschließen die Definition der Border-Linien.
  108.  
  109. StructBorder(Border, leftEdge, topEdge, frontPen, drawMode, NumLines, nextBorder);
  110. initialisiert eine Borderstruktur und bereitet IntuiStruct auf folgende Aufrufe von AddLine, Rectangle und BorderEnd vor. Default:
  111. backPen:=0;
  112. Beachten Sie, daß der Parameter NumLines nicht dem Feld Border.count entspricht. NumLines ist die Anzahl der Linien, nicht die der Eckpunkte.
  113.  
  114. Nach StructBorder gibt es zwei Möglichkeiten. Entweder folgen Numlines Aufrufe von AddLine oder ein (und nur ein) Aufruf von Rectangle.
  115. AddLine fügt jeweils eine Linie an die Borderstruktur an. Es müssen insgesammt genau soviele AddLines sein, wie mit NumLines angegeben wurden.
  116. Rectangle fügt gleich vier Linien auf einmal an, logischerweise ein geschlossenes Rechteck. Bei der Breite und Höhe sind die Randlinien selbst inklusiv, dh. die Eckpunkte sind width-1 bzw. height-1 voneinander entfernt. Pro Borderstruktur darf nur ein Rectangle definiert werden, und der Wert NumLines muß auf 4 gesetzt werden.
  117. BorderEnd schließt die Definition ab.
  118.  
  119. Mit FreeBorder(Border) kann der unter Border.xy belegte Speicher wieder freigegeben werden.
  120.  
  121. Menus
  122. Wer einmal ein umfangreiches Menu programmiert hat, der weiß, daß dies in eine ziemlich große Schreibarbeit ausartet. Erst muß für jeden Menupunkt (Item) und eventuell für die untergeordneten Punkte (SubItems) eine IntuiText-Struktur erzeugt werden. Dann wird für jedes Item und SubItem eine MenuItem-Struktur Initialisiert, die einen Zeiger auf die zugehörige IntuiText-Struktur enthält. Schließlich müssen die SubItems untereinander und mit ihrem Item, die Items untereinander und mit ihrem Menu(-kopf) verbunden werden, und endlich die Menus zum gesammten MenuStrip zusammengefügt werden.
  123. Mit dem vorliegenden Modul wird diese Prozedur enorm vereinfacht.
  124.  
  125. SubItem(ADR(Name), leftEdge, width, flags, mutualExclude, command);
  126. initialisiert eine MenuItem-Struktur (als SubItem) und die zugehörige IntuiText-Struktur. Parameter:
  127. leftEdge: Position des linken Rands der Selectbox des Subitems relativ zum linken Rand des Items, unter dem diese(s) SubItem steht/stehen
  128. width: Breite der Selectbox
  129. flags: MenuItemFlags (itemText muß gesetzt sein)
  130. mutualExclude: Ausschluß anderer Attributitems (Bit 0 für das oberste, also das zuletzt erzeugte SubItem)
  131. command: eventueller "Menuersatz-Key" (+rechte Amigataste), nur erforderlich, wenn das commSeq-Flag gesetzt ist
  132.  
  133. Alle anderen Felder werden später automatisch initialisiert (siehe LinkMenu). Die IntuiText-Struktur wird beim Aufruf von SubItem so initialisiert:
  134. frontPen:=0;backPen:=1;drawMode:=jam1;leftEdge:=0;topEdge:=0;
  135. iTextFont:=NIL;iText:=ADR(Name);nextText:=NIL;
  136. Wurde vorher (bzw. seit dem letzten Item-Aufruf) schon einmal SubItem aufgerufen, so wird das zuletzt definierte SubItem als nextItem in das gerade definierte SubItem eingetragen. Das bedeutet, wenn mehrmals hintereinander SubItem aufgerufen wird, sind die SubItems bereits von selbst miteinander verbunden. Das zuletzt definierte steht dabei als oberstes SubItem.
  137.  
  138. Das erzeugen von Items läuft fast genauso ab:
  139.  
  140. Item(ADR(Name), width, flags, mutualExclude, command);
  141. initialisiert eine MenuItem-Struktur und die zugehörige IntuiText-Struktur. Es muß hier kein leftEdge angegeben werden, da alle Items immer genau unter dem Menutitel stehen. Wurde seit dem letzten Item Aufruf ein oder mehrere male SubItem aufgerufen, so werden alle diese SubItems automatisch mit dem neuen Item verbunden. Ebenso sind alle seit dem letzten LinkMenu-Aufruf erzeugten Items mit diesem Item verbunden.
  142.  
  143. Sind alle Items und SubItems einer Menuspalte erzeugt, wird LinkMenu aufgerufen:
  144.  
  145. status:=LinkMenu(MenuStripPtr,Name,leftEdge,width,enabled);
  146. erzeugt eine Menu-Struktur und bindet diese an erster Stelle in den MenuStrip ein. Falls dies der erste Aufruf ist, sollte der MenuStrip-Pointer gleich NIL sein. LeftEdge und width beschreiben die Position und Größe der Menu-Selectbox in der Screen-Titelleiste. Enabled besagt, ob diese Menuspalte anwählbar (TRUE) oder gesperrt (FALSE) sein soll. Mit dem LinkMenu-Aufruf werden auch die Positionen aller Items und SubItems berechnet und in die MenuItem-Strukturen eingetragen. Das zuletzt definierte Item steht dabei direkt unter der Titelleiste, das vorletzte Item "StdHeight" Pixel darunter usw. Das erste (zuletzt definierte) SubItem eines Items steht direkt neben dem Item, alle nachfolgenden (vorher definierten) stehen "StdHeight" tiefer usw. Hat ein (Sub)Item das checkIt- oder das commSeq-Flag gesetzt, wird automatisch links seines Namens CheckWidth Pixel bzw. rechts CommWidth Pixel Platz reserviert.
  147. Ist status=TRUE, dann konnte das Menu korrekt erzeugt werden, ist es FALSE, dann trat ein Fehler auf. Es kann beispielsweise sein, daß für eine Item-Struktur kein Speicher mehr frei war. Falls ein neuer Versuch stattfinden soll, muß wieder mit dem untersten (Sub-)Item begonnen werden.
  148. Es wird empfohlen, Speichermangel mit Hilfe des AllocProc- Mechanismus abzufangen (siehe dort), da wenn status=FALSE ist, es für einen Teil des Speichers bereits "zu spät" ist. In der vorliegenden Version ist es möglich, das bei einem mißlungenen Versuch Speicher blockiert wird, der erst wieder bei Verlassen des Programms frei wird.
  149.  
  150. Es sei noch einmal erwähnt, daß die Items in umgekehrter Reihenfolge definiert werden müssen, wie sie später im Menu erscheinen sollen. Das zuletzt definierte Item steht an oberster Stelle und hat die "ItemNum"-mer 0, das zuvor definierte steht darunter und hat die Nummer 1 usw.
  151. Am besten zeigt dies ein Beispiel. Es soll folgendes Menu programmiert werden:
  152.  
  153. CommandsAttributes
  154. do nothingmagic
  155. do lessmore magic
  156. do something -this
  157. that
  158.  
  159.  
  160.  
  161. In Modula mit Hilfe von IntuiStruct sieht das dann so aus:
  162.  
  163. MenuStripPtr:=NIL;
  164. Item(ADR("more magic"), 80, MenuItemFlagSet[checkIt, itemText,
  165.   itemEnabled, highComp, checked], LONGSET[0], ASCII.nul);
  166. Item(ADR("magic"), 80, MenuItemFlagSet[checkIt, itemText,
  167.   itemEnabled, highComp], LONGSET[1], ASCII.nul);
  168. LinkMenu(MenuStripPtr, ADR("Attributes"), 240, 80, TRUE);
  169.  
  170. SubItem(ADR("that"), 64, 32, MenuItemFlagSet[itemText,
  171.   itemEnabled, highComp], LONGSET[], ASCII.nul);
  172. SubItem(ADR("this"), 64, 32, MenuItemFlagSet[itemText,
  173.   itemEnabled, highComp], LONGSET[], ASCII.nul);
  174. Item(ADR("do something"), 96, MenuItemFlagSet[itemText,
  175.   itemEnabled, highComp], LONGSET[], ASCII.nul);
  176. Item(ADR("do less"), 96, MenuItemFlagSet[itemText,
  177.   itemEnabled, highComp], LONGSET[], ASCII.nul);
  178. Item(ADR("do nothing"), 96, MenuItemFlagSet[itemText,
  179.   itemEnabled, highComp], LONGSET[], ASCII.nul);
  180. LinkMenu(MenuStripPtr, ADR("Commands"), 0, 64
  181. , TRUE);
  182.  
  183. Nach Ã¶ffnen des Windows braucht man nur noch SetMenuStrip(WindowPtr, MenuStripPtr) auszuführen.
  184.  
  185. Neu: mit der Prozedur UnlinkMenu(MenuStrip) kann der von einem ganzen MenuStrip belegte Speicher wieder freigegeben werden. Es wird das Menu, dessen Zeiger Ã¼bergeben wurde, alle folgenden Menus, alle Items und SubItems dealloziert. Soll eine einzelne Menuspalte dealloziert werden, muß sie vorher aus dem MenuStrip entfernt werden, ihr nextMenu-Feld muß in diesem Fall auf NIL stehen.
  186.  
  187. MenuNumbers
  188. Leider sin die Funktionen MENUNUM, ITEMNUM und SUBNUM (siehe Intuition Reference Manual S. 126/127) im M2Amiga Modul Intuition nicht Implementiert. In IntuiStruct ist dies nachgeholt. Dazu gehören auch die Konstanten MenuNull, NoItem und NoSub. Nützlich ist auch die Funktion MakeNum, wenn man zB. die Adresse eines bestimmten Items haben will, denn diese wird ja von IntuiStruct bei deren Definition geheimgehalten. MakeNum Ist gewissermaßen die Umkehrung von MenuNum, ItemNum und SubNum. Beispiel:
  189.  
  190. ItemAdr:=ItemAddress(MenuStripPtr,MakeNum(MenuNum,ItemNum,SubNum));
  191.  
  192. Neu: AllocProc, DeallocProc
  193. Version 1.0 von IntuiStruct verwendete immer das Bibliotheksmodul Heap für seine Speicherverwaltung. Um eine andere Speicherverwaltung verwenden zu können, wurden die Prozedurvariablen AllocProc und DeallocProc eingeführt. Als Beispiel sei hier "MemSystem" [bne] genannt, das demnächst auf einer Amok-Diskette erscheint und wirklich Interessantes zu bieten hat.
  194. Bevor sie eine der Prozeduren
  195. StructImage,
  196. LinkMenu, Item, SubItem,
  197. StructBorder
  198. benutzen, müssen die oben genannten Prozedurvariablen auf eine gültige AllocMem- und Deallocate-Prozedur gestellt werden.
  199. Vorsicht: diese Liste gilt nur für Version 1.3 und Ã¤ltere.
  200. Um wenigstens einigermaßen kompatibel zu bleiben, wurden die gleichen Prozedurtypen wie in Heap verwendet (AllocProcType, DeallocProcType). Die Konstanten CHIP und CHIPorFAST erklären sich wohl selbst.
  201.  
  202. Beispiel:
  203. IntuiStruct.AllocProc:=Heap.AllocMem;
  204. IntuiStruct.DeallocProc:=Heap.Deallocate;
  205.  
  206. oder:
  207. IntuiStruct.AllocProc:=MemSystem.AllocMem;
  208. IntuiStruct.DeallocProc:=MemSystem.Deallocate;
  209.  
  210. _____________________
  211.  
  212. Viel Spaß !
  213.   BeneDokumentation zu "IntuiStruct" Version 1.0aSeite 
  214. Autor: Nicolas Benezan, Postwiesenstr.2, D7000 Stuttgart 60
  215. Unterstützung von Intuition in Modula
  216.  
  217.